Remove `python-gil` requirement and enable free-threaded Python by ndgrigorian · Pull Request #2250 · IntelPython/dpctl

ndgrigorian · 2026-02-17T01:29:10Z

This PR removes the required python-gil dependency from the dpctl conda package workflow and enables free-threaded Python in extension modules

Adjustments are made to the SequentialOrderManager class such that the class is safe in free-threaded, including mutexes in the C++ class as a fall-back in case of (not recommended) simultaneous access to its members and methods

SequentialOrderManager now maintains thread-local storage for individual queue-to-manager-maps, such that each thread has its own manager per queue.

Queue and device caching, meanwhile, are global, to create a concept of default queues and devices that allows operations in extensions like dpnp (which rely on queues being the same for compute follows data) to operate on data passed between threads without copy.

In the futue, per-thread-queues and devices may prove more efficient, in which case, extensions will be asked to be made more robust (checking that context and device are the same, not using queue as a shortcut).

This PR builds on top of work already done removing the tensor submodule, which is pending migration to dpnp

Have you provided a meaningful PR description?
Have you added a test, reproducer or referred to an issue with a reproducer?
Have you tested your changes locally for CPU and GPU devices?
Have you made sure that new changes do not introduce compiler warnings?
Have you checked performance impact of proposed changes?
Have you added documentation for your changes, if necessary?
Have you added your changes to the changelog?
If this PR is a work in progress, are you opening the PR as a draft?

github-actions · 2026-02-17T03:16:12Z

View rendered docs @ https://intelpython.github.io/dpctl/pulls/2250/index.html

ndgrigorian · 2026-02-18T04:01:01Z

@antonwolfy @vlad-perevezentsev
won't be merged until after tensor submodule move, but take a look when you have time

coveralls · 2026-04-15T04:25:37Z

coverage: 75.45% (+0.06%) from 75.39% — feature/enable-free-threaded-python into master

free-threaded builds use a new GC that skips PyGC_Head, and this seems to cause some objects to change in size by ~16 bytes

…lobal

dpctl_capi singleton intiailization could cause deadlocks with updated order manager

vlad-perevezentsev

No more comments from my side
LGTM
Thank you @ndgrigorian

antonwolfy · 2026-06-15T10:24:43Z

+            // acquire gil to safely call into Python C API
+            py::gil_scoped_acquire acquire;
+
+            capi_ptr = new dpctl_capi();


Does switching from a function-local static to a heap pointer means ~dpctl_capi() and the whole Deleter finalization guard (lines 170-186) are now dead code — the held Python objects leak?
I guess leaking a process singleton is a defensible no-GIL trade-off, but it bypasses machinery that was deliberately written for interpreter finalization.

Do we need to add an explicit comment stating it's intentional?

antonwolfy · 2026-06-15T10:28:15Z

        self._state = _OrderManager(16)

-    def __dealloc__(self):
+    def __del__(self):


__dealloc__ was dead on a pure-Python class; renaming to __del__ makes it actually call SyclEvent.wait_for(...).

Under the free-threading, finalizers run on arbitrary threads and possibly during interpreter shutdown — combined with the existing weakref.finalize path, two finalizers now wait on events.

Confirm this is intended and that it's guarded against shutdown.

antonwolfy · 2026-06-15T10:32:00Z

+module.
+"""
+
+import concurrent.futures


SequentialOrderManager's map is threading.local(), so each worker thread gets a fresh, thread-private order manager.

The independent_threads/fork_join cases pass only because each thread does its own blocking wait() — the order manager is effectively a no-op for cross-thread coordination. Only explicit_event_passing does genuine cross-thread handoff (via explicit add_event_pair).

It seems we need at least to reframe the docstrings to say each thread keeps its own sequential order and cross-thread deps must be passed explicitly.

antonwolfy · 2026-06-15T10:34:16Z

@@ -0,0 +1,199 @@
+# Copyright 2020-2025 Intel Corporation


Seems we haven't to use the range:

Suggested change

# Copyright 2020-2025 Intel Corporation

# Copyright 2026 Intel Corporation

antonwolfy · 2026-06-15T10:37:09Z


 [project.optional-dependencies]
-coverage = ["Cython", "pytest", "pytest-cov", "coverage", "tomli"]
+coverage = ["Cython", "pytest", "coverage", "tomli"]


What is about the --cov-report term-missing below?
Actually ini.options has to be renamed to ini_options and it's only the reason why pytest is not failing with that change (removed pytest-cov).

antonwolfy · 2026-06-15T11:04:50Z

 }; // namespace

-PYBIND11_MODULE(_device_queries, m)
+PYBIND11_MODULE(_device_queries, m, py::mod_gil_not_used())


Should we update the example in docs/doc_sources/api_reference/dpctl_pybind11.rst with the same py::mod_gil_not_used()?

antonwolfy · 2026-06-15T11:20:29Z


 #include <algorithm>
 #include <cstddef>
+#include <mutex>


Missing <utility> include

antonwolfy · 2026-06-15T11:38:05Z

+            self.__device_map__[key] = dev
+            return dev
+
+    def _update_map(self, dev_map):


_update_map is public + unlocked — safe today (only called on the not-yet-shared _copy), but a foot-gun if ever called on the live global. We probably might need to consider locking it internally or clear documenting.

Or alternatively to revert back to cdef at least to make it inaccessible from the python code, i.e. to have more control when the method is called.

antonwolfy · 2026-06-15T11:43:23Z

+    def _update_map(self, dev_map):
        self.__device_map__.update(dev_map)

    def __copy__(self):


Seems not covered by any test

antonwolfy · 2026-06-15T11:49:31Z

+            self.__device_queue_map__[ctx_dev] = q
+            return q
+
+    def _update_map(self, dev_queue_map):


Same comment to _update_map

ndgrigorian changed the base branch from master to feature/uncouple-tensor-from-dpctl February 17, 2026 01:29

ndgrigorian force-pushed the feature/uncouple-tensor-from-dpctl branch from dcac1f6 to e450664 Compare February 17, 2026 02:08

ndgrigorian force-pushed the feature/enable-free-threaded-python branch from 085aece to 5dda977 Compare February 17, 2026 03:12

ndgrigorian force-pushed the feature/enable-free-threaded-python branch 4 times, most recently from 82e9a5e to a1d36ce Compare February 17, 2026 12:06

ndgrigorian marked this pull request as ready for review February 18, 2026 04:00

ndgrigorian requested review from antonwolfy and vlad-perevezentsev as code owners February 18, 2026 04:00

ndgrigorian force-pushed the feature/uncouple-tensor-from-dpctl branch 2 times, most recently from 6a5046b to 7d8bbc8 Compare April 7, 2026 18:36

ndgrigorian force-pushed the feature/uncouple-tensor-from-dpctl branch 2 times, most recently from b610ee3 to dd74214 Compare April 13, 2026 16:47

Base automatically changed from feature/uncouple-tensor-from-dpctl to master April 13, 2026 20:20

ndgrigorian force-pushed the feature/enable-free-threaded-python branch from 1b70ce6 to 1bc9c3d Compare April 15, 2026 04:18

ndgrigorian added 9 commits April 16, 2026 18:34

Make pybind11 modules GIL-free

dd08e01

Declare each Cython module free-threading compatible

5f4e279

add lock to warning check in onetrace_enabled context manager

54aafb2

Make ordermanager free-threading safe

245b42c

adds warning to syclinterface_diagnostics

52a8039

update caching for free-threaded python compatibility

3f97aab

remove python-gil as a requirement

05e0b80

remove pytest-cov as test dependencies

4ecd31d

update test_memory_create for free-threaded Python

c5d69b8

free-threaded builds use a new GC that skips PyGC_Head, and this seems to cause some objects to change in size by ~16 bytes

ndgrigorian force-pushed the feature/enable-free-threaded-python branch from 1bc9c3d to f1f0f76 Compare April 17, 2026 01:46

test dpctl built with and without free-threaded Python 3.14 in public CI

2823108

ndgrigorian added 4 commits April 16, 2026 19:11

adds trove classifier for Python free-threading status

ccb1bfe

fix missing parts of build/test matrices

2794463

make SequentialOrderManager thread-local and cached queues, devices g…

e9c20d5

…lobal

make __copy__ methods in cache classes hold locks

30a50e5

ndgrigorian force-pushed the feature/enable-free-threaded-python branch from f1f0f76 to 30a50e5 Compare April 17, 2026 02:11

ndgrigorian added 2 commits April 19, 2026 00:14

use Parameter.empty instead of _empty

24ade80

add order manager example

75c691c

ndgrigorian force-pushed the feature/enable-free-threaded-python branch 2 times, most recently from b37ca36 to 732f37d Compare April 21, 2026 06:38

fix potential hang in capi initialization

df6f452

dpctl_capi singleton intiailization could cause deadlocks with updated order manager

ndgrigorian force-pushed the feature/enable-free-threaded-python branch from 732f37d to df6f452 Compare April 21, 2026 06:39

ndgrigorian added 3 commits May 26, 2026 09:24

Merge branch 'master' into feature/enable-free-threaded-python

a0d7b1b

Merge branch 'master' into feature/enable-free-threaded-python

1c61a70

correct name in example

3a9ce96

vlad-perevezentsev reviewed Jun 2, 2026

View reviewed changes

Comment thread dpctl/utils/src/sequential_order_keeper.hpp Outdated

Comment thread dpctl/apis/include/dpctl4pybind11.hpp Outdated

Comment thread dpctl/_sycl_queue.pxd Outdated

address PR comments

a28065e

ndgrigorian requested a review from vlad-perevezentsev June 2, 2026 21:42

ndgrigorian added 2 commits June 2, 2026 14:53

run examples on free-threaded and GIL-enabled Python

31f0dbb

make examples free-threading compatible

3b675fc

vlad-perevezentsev reviewed Jun 3, 2026

View reviewed changes

Comment thread dpctl/_sycl_queue_manager.pyx

Comment thread dpctl/tests/test_sycl_queue_manager.py

ndgrigorian requested a review from vlad-perevezentsev June 3, 2026 17:06

vlad-perevezentsev previously approved these changes Jun 3, 2026

View reviewed changes

vchamarthi reviewed Jun 9, 2026

View reviewed changes

Comment thread pyproject.toml Outdated

bump minimum Cython version

819f48a

ndgrigorian dismissed vlad-perevezentsev’s stale review via 819f48a June 10, 2026 21:48

antonwolfy reviewed Jun 15, 2026

View reviewed changes

	# Copyright 2020-2025 Intel Corporation
	# Copyright 2026 Intel Corporation

Conversation

ndgrigorian commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Feb 17, 2026

Uh oh!

ndgrigorian commented Feb 18, 2026

Uh oh!

coveralls commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vlad-perevezentsev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

antonwolfy Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ndgrigorian commented Feb 17, 2026 •

edited

Loading

coveralls commented Apr 15, 2026 •

edited

Loading

antonwolfy Jun 15, 2026 •

edited

Loading